package intopo.game.impl.ipd;

/**
 * This interface represents the history of an Iterated Prisoner's Dilemma
 * game. This interface is used by classes derived from class {@code
 * IteratedPrisonerDilemmaPlayer} when calculating the action to be
 * performed at some iteration. This interface provides methods to query
 * past actions, actions at some iteration, the number of iterations, and
 * the payoff accumulated by the players.

 * @author <a href="mailto:plsm@det.ua.pt">Pedro Lopes da Silva Mariano</a>

 * @version 1.0
 */
interface IteratedPrisonerDilemmaHistory
{
	/**
	 * Returns {@code true} if the given player index cooperated at the
	 * specified iteration. Parameter {@code iteration} should be greater or
	 * equal to zero and less than the result of method {@code
	 * getNumberIterations()}.

	 * @param iteration the iteration to query
	 * @param playerIndex the player index, 0 or 1

	 * @return true if the given player cooperated at the specified
	 * iteration
	 */
	boolean cooperatedAtIteration (int iteration, int playerIndex);

	/**
	 * Returns {@code true} if the specified player cooperated in the past
	 * iteration. For example: {@code cooperated(1,0)} returns {@code true}
	 * if the player 0 cooperated in the previous iteration.

	 * <p>Parameter {@code iteration} should be greater than 0 and less than
	 * or equal to {@code getNumberIterations()}

	 * @param iteration the past iteration number
	 * @param playerIndex the player index, 0 or 1

	 * @return {@code true} if the given player cooperated at the past
	 * iteration
	 */
	boolean cooperatedInPastIteration (int iteration, int playerIndex);

	/**
	 * Returns the number of iterations that have ellapsed since the
	 * beginning of the game.

	 * @return the number of iterations that have ellapsed
	 */
	int getNumberOfIterations ();

	/**
	 * Get the current payoff the specified player. The value returned is
	 * the sum of all iterations payoff divided by the number of iterations.

	 * @return the player's payoff
	 */
	float getPayoff (int playerIndex);
}
